[release-1.7.3]: https://github.com/HuolalaTech/page-spy-web/releases/tag/v1.7.3
[public-data-event]: https://github.com/HuolalaTech/page-spy/blob/main/docs/plugin_zh.md#行为约定

import modalImg from '@/assets/image/screenshot/modal.png';
import replayImg from '@/assets/image/screenshot/replay-page.png';
import replayGif from '@/assets/image/screenshot/replay-page.gif';
import mpDataHarborImg from '@/assets/image/screenshot/mp-data-harbor.png';

## 是什么#what

日志回放是离线调试功能，允许你在问题发生后查看和分析当时的运行数据。通过回放历史日志，你可以像看录像一样重现问题场景，无需实时连接调试端。

<a href={replayGif} target="_blank">
  <img src={replayGif} />
</a>

## 为什么#why

PageSpy 的在线调试功能虽然强大，但要求客户端和调试端必须同时在线。这带来了一些限制：

- **人力成本高**：针对一个问题需要开发和测试同时在线配合
- **连接不稳定**：客户端退到后台或网络波动会导致连接断开
- **实时传输压力**：需要考虑数据体积和网络传输性能

为了解决这些问题，PageSpy 在 [1.7.3][release-1.7.3] 版本中提供了日志回放功能，让调试更加灵活自由。

## 开始使用#start-using

### 在浏览器中使用#browser

如果你需要完整的 PageSpy 功能，包括在线调试和离线回放，按以下步骤集成：

#### 第一步：引入 SDK 和插件#step-1

```html
<html>
  <head>
    <!-- 1. 加载 PageSpy -->
    <script src="{deployUrl}/page-spy/index.min.js"></script>
    <!-- 2. 加载 DataHarbor 插件：缓存离线日志数据，提供上传/下载功能 -->
    <script src="{deployUrl}/plugin/data-harbor/index.min.js"></script>
    <!-- 3. 加载 RRWeb 插件：记录用户操作轨迹（可选） -->
    <script src="{deployUrl}/plugin/rrweb/index.min.js"></script>

    <script>
      // 4. 注册插件，config 信息查看：https://github.com/HuolalaTech/page-spy/blob/main/packages/page-spy-plugin-data-harbor
      PageSpy.registerPlugin(new DataHarborPlugin(config));
      PageSpy.registerPlugin(new RRWebPlugin());

      // 5. 实例化 PageSpy
      window.$pageSpy = new PageSpy({
        // 如果不想 SDK 和调试端建立实时连接，可以开启离线模式
        // offline: true
      });
    </script>
  </head>
</html>
```

引入成功后，页面右下方会出现 PageSpy 的悬浮球。点击悬浮球，弹窗中会包含上传和下载按钮。

<a href={modalImg} target="_blank">
  <img src={modalImg} />
</a>

点击上传或下载按钮，即可保存离线日志数据。

#### 第二步：回放日志#step-2

进入调试端，点击顶部菜单「开始调试 - 日志回放」进入回放列表页面，选择上一步上传/下载的 JSON 数据即可开始回放！

<a href={replayImg} target="_blank">
  <img src={replayImg} />
</a>

#### 插件说明#plugins

- **DataHarborPlugin**：收集和存储离线日志数据，提供上传/下载功能
- **RRWebPlugin**（可选）：使用 [rrweb]({VITE_PLUGIN_RRWEB}) 记录 DOM 更新和用户操作轨迹，在调试端的「日志回放」面板左侧可以看到页面的操作录像

### 使用 O-Spy#use-ospy

如果你只需要离线日志回放功能，推荐使用 [O-Spy](/o-spy)。它是即插即用的 SDK，无需部署服务器，内置了 PageSpy、DataHarborPlugin 和 RRWebPlugin 的最佳实践配置。

与框架无关，可以任选一种方式引入：

import { ImportGuide } from '@/pages/OSpy/components/ImportGuide';

<ImportGuide />

引入成功后，页面右下角会出现可拖拽的"问题反馈"组件。

#### 自定义主题#customize-example

import { CustomizeExample } from '@/pages/OSpy/components/Customize';

<CustomizeExample />

### 在小程序中使用#mp

小程序环境也支持离线日志回放，步骤如下：

#### 第一步：安装小程序专用插件#mp-step-1

```bash
yarn add @huolala-tech/page-spy-plugin-mp-data-harbor
```

#### 第二步：注册插件#mp-step-2

```ts
import PageSpy from '@huolala-tech/page-spy-wechat';
import DataHarborPlugin from '@huolala-tech/page-spy-plugin-mp-data-harbor';

// 注册插件，config 信息查看：https://github.com/HuolalaTech/page-spy/blob/main/packages/page-spy-plugin-mp-data-harbor
const $dataHarborPlugin = new DataHarborPlugin(config)
PageSpy.registerPlugin($dataHarborPlugin);

const $pageSpy = new PageSpy({
  // ...
})
```

#### 第三步：上传离线日志#mp-step-3

有两种方式可以上传离线日志：

**方式一：代码调用**

```ts
$dataHarborPlugin.upload().then(() => {
  console.log('上传成功');
})
```

**方式二：使用调试菜单**

注册小程序 DataHarbor 插件后，PageSpy 的调试菜单中会出现「上传离线日志」按钮，点击即可上传：

<a href={mpDataHarborImg} target="_blank">
  <img style={{width: 375}} src={mpDataHarborImg} />
</a>

## 延伸阅读#read-more

### 工作原理#how-it-works

日志回放基于 [DataHarborPlugin]({VITE_PLUGIN_DATA_HARBOR}) 插件实现。该插件通过监听 PageSpy 内部的 [`"public-data"` 事件](./plugins#convention)，自动收集运行时产生的所有数据。

### 平台差异#platform-differences

不同平台在日志回放功能上存在以下差异：

| 功能 | 浏览器 | 小程序 |
| --- | --- | --- |
| 数据上传 | ✅ 支持 | ✅ 支持 |
| 数据下载 | ✅ 支持 | ❌ 不支持 |
| 界面录制（RRWebPlugin） | ✅ 支持 | ❌ 不支持 |

### FAQ#faq

#### 1. 如何手动操作上传/下载日志？

详细说明请查看 [DataHarborPlugin API 文档](./data-harbor#onOfflineLog)。

#### 2. 离线日志存储在哪里？

DataHarborPlugin 收到数据后的处理流程：

1. 数据首先存储在内存数组中
2. 当内存中的数据达到临界值（默认 10MB）时，自动写入临时文件
3. 用户可以随时上传数据到服务器，或下载到本地保存

你可以自定义内存临界值：

```ts
new DataHarborPlugin({
  maximum: 1 * 1024 * 1024, // 内存中的数据达到 1MB 时写入临时文件
})
```

#### 3. 离线日志会影响应用性能吗？

DataHarborPlugin 经过性能优化：

- 使用异步处理，不阻塞主线程
- 自动控制内存使用，防止内存溢出
- 数据压缩后存储，减少空间占用